home *** CD-ROM | disk | FTP | other *** search
/ The Fatted Calf / The Fatted Calf.iso / Applications / Utilities / Pastry / DeveloperNotes / README < prev   
Encoding:
Text File  |  1994-02-28  |  7.2 KB  |  199 lines
  1. $Id: README,v 1.3 1994/02/26 03:38:44 davis Exp $
  2.  
  3.  
  4.         Notes on Developing Custom Inspectors for Pastry
  5.         ------------------------------------------------
  6.  
  7. Steps
  8. -----
  9.  
  10.     Developing inspectors for Pastry is simple if you are familiar
  11. with NeXTSTEP programming, including Objective-C and Interface
  12. Builder.  Just follow these steps:
  13.  
  14.  
  15. o  Use Project Builder to create a new bundle.  You can name the
  16.    bundle whatever you want as long as it doesn't conflict with the
  17.    other bundles in the directory you plan to put it in -- something
  18.    related to the type of information it will inspect is good.
  19.  
  20.  
  21. o  If you are using NeXTSTEP 3.2, press the "Attributes" button in PB
  22.    and change the extension of the bundle to "pane".  (If you are
  23.    using 3.1, you'll need to use some other method to change the
  24.    default extension "bundle" to the one Pastry expects.  You can do
  25.    this in the Makefiles or by renaming it manually after you have
  26.    built it.)
  27.  
  28.  
  29. o  Create a class that conforms to the InspectorPane protocol.  In
  30.    choosing a name for you class, try to pick something that is
  31.    unlikely to be used by someone else who may write bundles for
  32.    Pastry.  I've included "InspectorPane.h" which declares the
  33.    protocol that your class must implement.  It contains 3 methods --
  34.    here's a quick description of each one:
  35.  
  36.    + (const NXAtom *)types
  37.  
  38.      This method should return a NULL-terminated list of all of the
  39.      pasteboard types your inspector can inspect.  Pastry will send
  40.      the message when it loads your class, just before the
  41.      InspectorPanel becomes key for the first time, to find out what
  42.      it does.  Pastry loads panes from directories in this order:
  43.  
  44.         Pastry.app
  45.         ~/Library/Pastry
  46.         /LocalLibrary/Pastry
  47.  
  48.      The first pane that Pastry encounters that can inspect a certain
  49.      type will be assigned the task of inspecting that type.  If your
  50.      pane can inspect both ASCII and RTF, for example, and Pastry
  51.      loads some other pane that inspects ASCII before it loads yours,
  52.      your pane will not be called upon to inspect ASCII.  But your
  53.      pane will be called upon to inspect RTF if no previous class
  54.      inspects that type.
  55.  
  56.      There is no way to determine which panes in the same directory
  57.      will be loaded first.  If you want to guarantee that your pane
  58.      will be loaded before some other pane, place it in a directory
  59.      earlier in Pastry's pane load path.  To replace the default
  60.      inspectors for Text (ASCII and RTF), Images, Fonts, and Rulers,
  61.      replace the panes in Pastry.app with your panes.
  62.  
  63.  
  64.    - updateFromStream:(NXStream *)stream withType:(NXAtom)type
  65.  
  66.      When it is time for your pane to present a representation of the
  67.      pasteboard information to the user, Pastry will send this method
  68.      to your class.  The stream argument is the information read from
  69.      the pasteboard that your class should inspect.  (It's already
  70.      open for reading.)  The type argument is the type of data in the
  71.      stream, a type that your class has claimed to inspect.  Your
  72.      class can read from the stream, but don't close or free it.
  73.  
  74.      Pastry will send this message only if the pasteboard information
  75.      has changed, so there is no need for your class to check that.
  76.  
  77.      Your class should read the appropriate information from the
  78.      stream and change the appearance of its view (see below) to
  79.      reflect the information.  The panel that the view is in will have
  80.      its display and flush disabled before this message is sent -- and
  81.      it will displayed and flushed after your class returns from the
  82.      message.
  83.  
  84.  
  85.    - (View *)view
  86.  
  87.      Pastry will ask your class (at any time) for a View.  It will
  88.      position that view in the Inspector Panel and display it at the
  89.      appropriate times.  It is this view that your class should modify
  90.      when it receives an -updateFromStream:withType: method.  If your
  91.      class is a View, it could just return self.
  92.  
  93.      Pastry will free the pane, not the view so make sure your class
  94.      frees everything it allocates.
  95.  
  96.  
  97.    Your class may also implement one or both of these methods:
  98.  
  99.    - didSwapIn:sender
  100.    - didSwapOut:sender
  101.  
  102.    If it does, your class will receive notification immediately after
  103.    its view is moved into and out of the Inspector Panel.
  104.  
  105.  
  106. o  Use Project Builder to add your class, the InspectorPane.h header,
  107.    and any other source files to the bundle project.  If your bundle
  108.    contains more than one class, make sure the one that conforms to
  109.    the InspectorPane protocol is the principal class.
  110.  
  111.  
  112. o  Add any NIB interfaces and other resources required by your class
  113.    using PB. 
  114.  
  115.  
  116. o  Compile your bundle and place it in one of the pane search
  117.    directories listed above.
  118.  
  119.  
  120.  
  121.  
  122.  
  123. Suggestions
  124. -----------
  125.  
  126.     Here are some suggestions for implementing the pane.
  127.  
  128.  
  129. o  If your pane will contain several views or controls, create a NIB
  130.    that contains a window.  Put your views and controls in this
  131.    window.  When Pastry asks for your pane's view, return the content
  132.    view of the window.  You can do this with something like
  133.  
  134.     view = [window setContentView:[[View alloc] init]];
  135.  
  136.    where view is an instance variable of your class.  The -view method
  137.    should return this variable.
  138.  
  139.    Doing this will allow you to coordinate the various controls in
  140.    your pane and it will allow you to set various connections and
  141.    autosizing attributes in IB.
  142.  
  143.    It would be nice to load the NIB as late as possible, at the first
  144.    request for the view or the first request for an update, for
  145.    example.  In your -update... method, you could do this:
  146.  
  147.     if (!window)
  148.        [self _loadNib];
  149.  
  150.    and something similar in the -view method.
  151.  
  152.  
  153. o  Remember that the inspector panel is resizable and your view will
  154.    be sized along with it.  If you use the content view suggestion
  155.    above, be sure to make the other views in the window (i.e. the
  156.    subviews of the window's content view) resizable, or anchor them
  157.    correctly to an edge of the content view.  (Also if you are using
  158.    the context view suggestions, select the window in your NIB and set
  159.    all sides non-sizable in the size inspector.)
  160.  
  161.  
  162. o  Pastry attempts to keep the Inspector Panel from becoming the key
  163.    window.  For this reason, any text fields in your pane should not
  164.    be editable or selectable, unless they must be for your pane to
  165.    work properly.
  166.  
  167.  
  168. o  Your class should not try to overstep its bounds -- don't try to
  169.    mess with the Inspector Panel or NXApp or any other such weirdness.
  170.    Bad things would surely result.
  171.  
  172.  
  173.  
  174.  
  175.  
  176. Sample
  177. ------
  178.  
  179.     I've included the source for a sound inspector pane.  It
  180. doesn't do much, but it illustrates the stuff I've mentioned above.
  181. To try it out, type "make install INSTALLDIR=/LocalLibrary/Pastry" or
  182. wherever you want it installed.  Make sure the installation directory
  183. exists before you make.  If you are using NeXTSTEP 3.1, the final
  184. product of the make will be "Sound.bundle" -- rename this to
  185. "Sound.pane".
  186.  
  187.  
  188.  
  189. Future Compatibility
  190. --------------------
  191.  
  192.     Since Pastry is still in its early days, this API could very
  193. well change -- I make no claims that it will stay constant.  Luckily,
  194. inspectors are fairly easy to write and probably won't require much
  195. change even if I do change the API.  You'll probably be better off if
  196. you stick to my suggestions, because that's how I develop panes.
  197.  
  198.  
  199.